 /*******************************************************************************
  * Copyright (c) 2000, 2005 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.ui.console;

 /**
  * A pattern match listener is registered with a <code>TextConsole</code>,
  * and is notified when its pattern has been matched to contents in
  * that console. A pattern match listener can be registered with a console
  * programmatically or via the <code>consolePatternMatchListeners</code> extension
  * point.
  * <p>
  * Following is an example console pattern match listener extension definition.
  * </pre>
  * &lt;extension point="org.eclipse.ui.console.consolePatternMatchListeners"&gt;
  * &lt;consolePatternMatchListener
  * id="com.example.ConsolePatternMatcher"
  * regex=".*foo.*"
  * class="com.example.ConsolePatternMatcher"&gt;
  * &lt;/consolePatternMatchListener&gt;
  * &lt;/extension&gt;
  * </pre>
  * Attributes are specified as follows:
  * <ul>
  * <li><code>id</code> - a unique identifier for the pattern match listener</li>
  * <li><code>regex</code> - regular expression to match</li>
  * <li><code>class</code> - fully qualified name of the Java class implementing
  * <code>org.eclipse.ui.console.IPatternMatchListenerDelegate</code></li>
  * </ul>
  * </p>
  * <p>
  * Optionally a <code>qualifier</code> attribute may be specified to improve performance
  * of regular expression matching. A qualifier specifies a simple regular expression used to
  * qualify lines for the search. Lines that do not contain the qualifier are not considered.
  * </p>
  * <p>
  * Optionally an <code>enablement</code> expression may be provided to specify
  * which console(s) a pattern matcher should be contributed to.
  * </p>
  * <p>
  * Clients may implement this interface directly if registering a pattern match listener with
  * a text console programmatically. Clients contributing a pattern match listener via an
  * extension implement <code>IPatternMatchListenerDelegate</code> instead.
  * </p>
  * @see org.eclipse.ui.console.TextConsole
  * @since 3.1
  */
 public interface IPatternMatchListener extends IPatternMatchListenerDelegate {
     /**
      * Returns the pattern to be used for matching. The pattern is
      * a string representing a regular expression.
      *
      * @return the regular expression to be used for matching
      */
     public String getPattern();
     
     /**
      * Returns the flags to use when compiling this pattern match listener's
      * regular expression, as defined by by <code>Pattern.compile(String regex, int flags)</code>
      *
      * @return the flags to use when compiling this pattern match listener's
      * regular expression
      * @see java.util.regex.Pattern#compile(java.lang.String, int)
      */
     public int getCompilerFlags();
     
     /**
      * Returns a simple regular expression used to identify lines that may
      * match this pattern matcher's complete pattern, or <code>null</code>.
      * Use of this attribute can improve performance by disqualifying lines
      * from the search. When a line is found containing a match for this expression,
      * the line is searched from the beginning for this pattern matcher's
      * complete pattern. Lines not containing this pattern are discarded.
      *
      * @return a simple regular expression used to identify lines that may
      * match this pattern matcher's complete pattern, or <code>null</code>
      */
     public String getLineQualifier();
     
 }

